Montage is a general astronomical image toolkit with facilities for reprojection, background matching, coaddition and visualization. It can be used as a set of command-line tools (Linux, OS X and Windows), C library calls (Linux and OS X) and as Python binary extension modules.
Montage source code can be downloaded from GitHub (https://github.com/Caltech-IPAC/Montage). The Python package can be installed from PyPI ("pip install MontagePy"). See http://montage.ipac.caltech.edu/ for more information.
MontagePy.main modules: mDiffExec¶
A large percentage of the Montage modules focus on processing a set of images (often retrieved from a mission archive); projecting them to a common frame, adjusting their background levels as a set, and coadding them into a mosaic.
This page is focused on the details of one of these modules: mDiffExec. For a broader context, please see Building a Mosaic with Montage or the one shot version if you just want to see the commands.
Note: The MontagePy python package has no external dependencies. We include other utilities on this page to aid in visualizing MontagePy package results.
from MontagePy.main import mDiffExec, mViewer
help(mDiffExec)
mDiffExec Example¶
mDiffExec is a general utility for creating a set of differences images. It's most common use is in the process of evaluating overlap area in a set of images as part of background rectification. That process consists of taking the output of the overlaps calculation (mOverlaps) and for each overlap pair doing the difference (mDiff), fitting it to determine offset between those two images (mFitplane).
There are two ways to do this in bulk. We can either generate all the differences first, then fit them all or we can loop over the differences, generating and fitting that difference before moving on to the next. This first approach uses more disks space as all the differences have to be stored in between steps. The second can clean up as it goes.
Obviously the second approach is preferable unless you want to keep the differences (possibly for quality evaluation).
mDiffExec is part of the first approach. It runs mFitplane on difference file from the input list and stores the result in a table. This table will usually be handed to mBgModel to determine what corrections to make to each image to minimize background differences.
At this point in the processing, we already have a set of "like" images (same projection) and have made a list of all the overlaps (normally using mOverlaps). mDiffExec loops over this list and generates all the difference images in a subdirectory:
import os
try:
os.makedirs('work/M17/diffs')
except:
pass
rtn = mDiffExec('M17/projected',
'M17/diffs.tbl',
'M17/M17.hdr',
'work/M17/diffs')
print(rtn)
The list of overlaps, as generated by mOverlaps, constructs difference image names based on the row numbers of the two files in the original image metadata list. Here we show diff.000001.000011.fits and diff.000001.000006.fits (the differences between the image that contains the center of M17 and the images to the right and left respectively):
from IPython.display import HTML, display, Image
rtn = mViewer("-ct 1 -gray work/M17/diffs/diff.000001.000011.fits \
-2s max gaussian-log -out work/M17/diff.000001.000011.png", "", mode=2)
rtn = mViewer("-ct 1 -gray work/M17/diffs/diff.000001.000006.fits \
-2s max gaussian-log -out work/M17/diff.000001.000006.png", "", mode=2)
display(HTML("<table><tr><td><img src='work/M17/diff.000001.000011.png'></td> \
<td><img src='work/M17/diff.000001.000006.png'></td></tr></table>"))
 |  |
and where it is in the mosaic:
rtn = mViewer("-color lightgray -imginfo M17/pimages.tbl \
-color black -imginfo M17/dimages.tbl \
-ct 1 -gray M17/mosaic.fits -2s max gaussian-log \
-out work/M17/mosaic_diffexec.png",
"", mode=2)
Image(filename='work/M17/mosaic_diffexec.png')
mDiffExec Error Handling¶
If mDiffExec encounters an error, the return structure will just have two elements: a status of 1 ("error") and a message string that tries to diagnose the reason for the error.
For instance, if the user specifies a table that doesn't exist:
rtn = mDiffExec("M17/projected",
"M17/unknown.tbl",
"M17/M17.hdr",
"work/M17/diffs")
print(rtn)
Classic Montage: mDiffExec as a Stand-Alone Program¶
mDiffExec Unix/Windows Command-line Arguments¶
mDiffExec can also be run as a command-line tool in Linux, OS X, and Windows:
Usage: mDiffExec [-p projdir] [-d] [-n(o-areas)] [-s statusfile] diffs.tbl template.hdr diffdir
If you are writing in C/C++, mDiffExec can be accessed as a library function:
/*-*****************************************************************/ /* */ /* mDiffExec */ /* */ /* Read the table of overlaps found by mOverlap and rune mDiff to */ /* generate the difference files. */ /* */ /* char *path Path to images to be diffed. */ /* char *tblfile Table file list of images to diff. */ /* char *template FITS header file used to define the desired */ /* output. */ /* */ /* char *diffdir Directory for temporary output diff files. */ /* int noAreas Flag indicating there are no area images. */ /* int debug Debug flag. */ /* */ /*******************************************************************/ struct mDiffExecReturn *mDiffExec(char *path, char *tblfile, char *template, char *diffdir, int noAreas, int debugin)
Return Structure
struct mDiffExecReturn
{
int status; // Return status (0: OK, 1:ERROR)
char msg [1024]; // Return message (for error return)
char json[4096]; // Return parameters as JSON string
int count; // Number of differences
int failed; // Number of differences that failed
int warning; // Number of fits to differences that produced warnings
};